﻿//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: ITransactionStorage.cs
//
//  Description: Provides functionality for storages supporting transactions.
// 
//--------------------------------------------------------------------------

using System;
using System.Data;

namespace Chili.Opf3.Storages
{
	/// <summary>This interface is implemented by a storage that supports transactions.</summary>
	/// <remarks>
	/// This interface is implemented by storages that support transactions. A transaction is an 
	/// atomic action that can be rolled back until not committed. Transaction are usually used during
	/// save processes to make sure that no corrupted data is written to the storage. 
	/// When starting a new transaction it is possible to set a 
	/// <see cref="System.Data.IsolationLevel">IsolationLevel</see> that specifies the level of the transaction.
	/// </remarks>
	/// <example>
	/// For examples how to implement your own storage see: 
	/// <see cref="Opf3.Storages.MsSql.MsSqlStorage">MsSqlStorage</see>, 
	/// <see cref="Opf3.Storages.Oracle.OracleStorage">OracleStorage</see> or any other storage that comes with the
	/// framework.
	/// </example>
	public interface ITransactionStorage : IStorage
	{
		/// <summary>
		/// Starts a new transaction.
		/// </summary>
		/// <returns>Returns a class that implements the <a href="ITransaction">ITransaction</a> interface if the transaction could be started. Null otherwise.</returns>
		/// <param name="level"><see cref="System.Data.IsolationLevel">IsolationLevel</see> of the transaction.</param>
		Transaction StartTransaction(IsolationLevel level);

		/// <summary>
		/// Starts a new transaction.
		/// </summary>
		/// <returns>Returns a class that implements the <a href="ITransaction">ITransaction</a> interface if the transaction could be started. Null otherwise.</returns>
		Transaction StartTransaction();

		/// <summary>
		/// Commits the current open transaction on the storage. If no transaction 
		/// is open no exception should be thrown.
		/// </summary>
		void Commit();

		/// <summary>
		/// Rolls the current open transaction back. If no transaction is open no
		/// exception should be thrown.
		/// </summary>
		void Rollback();

		/// <summary>Returns the current active transaction.</summary>
		/// <value>The current active transaction or null if no transaction is active.</value>
		Transaction ActiveTransaction { get; }

		/// <summary>Returns whether a transaction is currently active.</summary>
		/// <value>True if a transaction is currently open.</value>
		bool IsTransactionActive { get; }

		/// <summary>
		/// Event is fired if a transaction has been started.
		/// </summary>
		/// <remarks>This event is fired each time a new transaction is successfully started.</remarks>
		event EventHandler<EventArgs> TransactionStart;

		/// <summary>
		/// Event is fired if a transaction has been committed.
		/// </summary>
		/// <remarks>This event is fired each time a new transaction is successfully committed.</remarks>
		event EventHandler<EventArgs> TransactionCommit;

		/// <summary>
		/// Event is fired if a transaction has been aborted.
		/// </summary>
		/// <remarks>
		/// This event is fired each time a new transaction is successfully rolled back.
		/// </remarks>
		event EventHandler<EventArgs> TransactionRollback;
	}
}
